;;;###autoload
(defun read-passwd (prompt &optional confirm default)
- "Read a password, prompting with PROMPT, and return it.
+ "Read a password, prompting with PROMPT, and return password as a string.
If optional CONFIRM is non-nil, read the password twice to make sure.
Optional DEFAULT is a default password to use instead of empty input.
(defun read-answer (question answers)
"Read an answer either as a complete word or its character abbreviation.
Ask user a question and accept an answer from the list of possible answers.
+Return the long answer even when accepting short ones.
QUESTION should end in a space; this function adds a list of answers to it.
When `read-answer-short' is non-nil, accept short answers.
-Return a long answer even in case of accepting short ones.
-
When `use-dialog-box' is t, pop up a dialog window to get user input."
(let* ((short (if (eq read-answer-short 'auto)
(or use-short-answers
(defvar read-envvar-name-history nil)
(defun read-envvar-name (prompt &optional mustmatch)
- "Read environment variable name, prompting with PROMPT.
+ "Read and return an environment variable name string, prompting with PROMPT.
Optional second arg MUSTMATCH, if non-nil, means require existing envvar name.
If it is also not t, RET does not exit if it does non-null completion."
(completing-read prompt
"Text string to display as the sample text for `read-face-name'.")
(defun read-face-name (prompt &optional default multiple)
- "Read one or more face names, prompting with PROMPT.
+ "Read and return one or more face names, strings, prompting with PROMPT.
PROMPT should not end in a space or a colon.
If DEFAULT is non-nil, it should be a face (a symbol) or a face
(pattern &optional face frame maximum width))
(defun read-face-font (face &optional frame)
- "Read the name of a font for FACE on FRAME.
+ "Read and return the string name of the font for FACE on FRAME.
If optional argument FRAME is nil or omitted, use the selected frame."
(let ((completion-ignore-case t))
(completing-read (format-message
(defun read-color (&optional prompt convert-to-RGB allow-empty-name msg
foreground face)
- "Read a color name or RGB triplet.
+ "Read a color name or RGB triplet, return a string, the color name or RGB.
Completion is available for color names, but not for RGB triplets.
RGB triplets have the form \"#RRGGBB\". Each of the R, G, and B
;;; Commands to add/delete file-local/directory-local variables.
(defun read-file-local-variable (prompt)
- "Read file-local variable using PROMPT and completion.
+ "Read the name of a file-local variable using PROMPT and completion.
+Return the symbol of the variable, or nil if the user entered empty or
+null name.
Intended to be used in the `interactive' spec of
`add-file-local-variable', `delete-file-local-variable',
`add-dir-local-variable', `delete-dir-local-variable'."
(and (stringp variable) (intern variable))))
(defun read-file-local-variable-value (variable)
- "Read value of file-local VARIABLE using completion.
+ "Read and return the value of a file-local VARIABLE using completion.
Intended to be used in the `interactive' spec of
`add-file-local-variable' and `add-dir-local-variable'."
(cond
default)))))
(defun read-file-local-variable-mode ()
- "Read per-directory file-local variable's mode using completion.
+ "Read the name of a per-directory file-local variable's mode using completion.
+Return the symbol of the variable, or nil if the user entered empty or
+null name.
Intended to be used in the `interactive' spec of
`add-dir-local-variable', `delete-dir-local-variable'."
(let* ((default (and (symbolp major-mode) (symbol-name major-mode)))
non-empty string that was inserted by this function.
(If DEFAULT-DIRNAME is omitted, DIR combined with INITIAL is used,
or just DIR if INITIAL is nil.)
+Return the directory as a string.
If the user exits with an empty minibuffer, this function returns
an empty string. (This can happen only if the user erased the
pre-inserted contents or if `insert-default-directory' is nil.)
(defun read-multilingual-string (prompt &optional initial-input input-method)
"Read a multilingual string from minibuffer, prompting with string PROMPT.
+Return the string thus read.
The input method selected last time is activated in minibuffer.
If optional second argument INITIAL-INPUT is non-nil, insert it in the
minibuffer initially.
(defun read-charset (prompt &optional default-value initial-input)
"Read a character set from the minibuffer, prompting with string PROMPT.
It must be an Emacs character set listed in the variable `charset-list'.
+Return the charset as a symbol.
Optional arguments are DEFAULT-VALUE and INITIAL-INPUT.
DEFAULT-VALUE, if non-nil, is the default value.
;;;###autoload
(defun read-hiragana-string (prompt &optional initial-input)
"Read a Hiragana string from the minibuffer, prompting with string PROMPT.
-If non-nil, second arg INITIAL-INPUT is a string to insert before reading."
+If non-nil, second arg INITIAL-INPUT is a string to insert before reading.
+Return the string read from the minibuffer."
(read-multilingual-string prompt initial-input "japanese-hiragana"))
;;
"?" #'self-insert-and-exit)
(defun read-no-blanks-input (prompt &optional initial inherit-input-method)
- "Read a string from the terminal, not allowing blanks.
+ "Read and return a string from the terminal, not allowing blanks.
Prompt with PROMPT. Whitespace terminates the input. If INITIAL is
non-nil, it should be a string, which is used as initial input, with
point positioned at the end, so that SPACE will accept the input.
(if (listp default) default (list default)))))
(defun read-file-name (prompt &optional dir default-filename mustmatch initial predicate)
- "Read file name, prompting with PROMPT and completing in directory DIR.
+ "Read a file name, prompting with PROMPT and completing in directory DIR.
+Retrun the file name as a string.
The return value is not expanded---you must call `expand-file-name'
yourself.
(or result input))))
(defun read-regexp-case-fold-search (regexp)
- "Return a value for `case-fold-search' based on REGEXP and current settings.
+ "Return the value for `case-fold-search' based on REGEXP and current settings.
REGEXP is a string as returned by `read-regexp'."
(let ((fold (get-text-property 0 'case-fold regexp)))
(cond
"Minor mode used for completion in `read-extended-command'.")
(defun read-extended-command (&optional prompt)
- "Read command name to invoke via `execute-extended-command'.
+ "Read and return name of command to invoke via `execute-extended-command'.
Use `read-extended-command-predicate' to determine which commands
to include among completion candidates.
"Keymap used for completing shell commands in minibuffer.")
(defun read-shell-command (prompt &optional initial-contents hist &rest args)
- "Read a shell command from the minibuffer.
+ "Read a shell command from the minibuffer, and return it as a string.
The arguments are the same as the ones of `read-from-minibuffer',
except READ and KEYMAP are missing and HIST defaults
to `shell-command-history'."
(defvar read-from-kill-ring-history)
(defun read-from-kill-ring (prompt)
"Read a `kill-ring' entry using completion and minibuffer history.
-PROMPT is a string to prompt with."
+PROMPT is a string to prompt with.
+Return the entry as a string."
;; `current-kill' updates `kill-ring' with a possible interprogram-paste
(current-kill 0)
(let* ((history-add-new-input nil)
(string= string ""))
(defun read-signal-name ()
- "Read a signal number or name."
+ "Read a signal number or name.
+Return the signal number, if the user entered a number, otherwise
+the signal symbol."
(let ((value
(completing-read "Signal code or name: "
(signal-names)
(defvar read-key-delay 0.01) ;Fast enough for 100Hz repeat rate, hopefully.
(defun read-key (&optional prompt disable-fallbacks)
- "Read a key from the keyboard.
+ "Read a key from the keyboard, return the event thus read.
Contrary to `read-event' this will not return a raw event but instead will
obey the input decoding and translations usually done by `read-key-sequence'.
So escape sequences and keyboard encoding are taken into account.
"The default history for the `read-number' function.")
(defun read-number (prompt &optional default hist)
- "Read a numeric value in the minibuffer, prompting with PROMPT.
+ "Read from the minibuffer and return a numeric value, prompting with PROMPT.
DEFAULT specifies a default value to return if the user just types RET.
For historical reasons, the value of DEFAULT is always inserted into
PROMPT, so it's recommended to use `format' instead of `format-prompt'
included in the resulting string. If nil, no prompt will be
inserted in the buffer.
+When the user exits recursive edit, this function returns the
+edited STRING.
+
Also see `string-edit'."
(string-edit
prompt
DEFUN ("read-non-nil-coding-system", Fread_non_nil_coding_system,
Sread_non_nil_coding_system, 1, 1, 0,
- doc: /* Read a coding system from the minibuffer, prompting with string PROMPT. */)
+ doc: /* Read a coding system from the minibuffer, prompting with string PROMPT.
+Return the symbol of the coding-system. */)
(Lisp_Object prompt)
{
Lisp_Object val;
DEFUN ("read-coding-system", Fread_coding_system, Sread_coding_system, 1, 2, 0,
doc: /* Read a coding system from the minibuffer, prompting with string PROMPT.
If the user enters null input, return second argument DEFAULT-CODING-SYSTEM.
+Return the coding-system's symbol, or nil if both the user input and
+DEFAULT-CODING-SYSTEM are empty or null.
Ignores case when completing coding systems (all Emacs coding systems
are lower-case). */)
(Lisp_Object prompt, Lisp_Object default_coding_system)
DEFUN ("read-char", Fread_char, Sread_char, 0, 3, 0,
doc: /* Read a character event from the command input (keyboard or macro).
-It is returned as a number.
+Return the character as a number.
If the event has modifiers, they are resolved and reflected in the
returned character code if possible (e.g. C-SPC yields 0 and C-a yields 97).
If some of the modifiers cannot be reflected in the character code, the
}
DEFUN ("read-event", Fread_event, Sread_event, 0, 3, 0,
- doc: /* Read an event object from the input stream.
+ doc: /* Read and return an event object from the input stream.
If you want to read non-character events, consider calling `read-key'
instead. `read-key' will decode events via `input-decode-map' that
DEFUN ("read-char-exclusive", Fread_char_exclusive, Sread_char_exclusive, 0, 3, 0,
doc: /* Read a character event from the command input (keyboard or macro).
-It is returned as a number. Non-character events are ignored.
+Return the character as a number. Non-character events are ignored.
If the event has modifiers, they are resolved and reflected in the
returned character code if possible (e.g. C-SPC yields 0 and C-a yields 97).
If some of the modifiers cannot be reflected in the character code, the
DEFUN ("read-from-minibuffer", Fread_from_minibuffer,
Sread_from_minibuffer, 1, 7, 0,
- doc: /* Read a string from the minibuffer, prompting with string PROMPT.
+ doc: /* Read and return a string from the minibuffer, prompting with string PROMPT.
The optional second arg INITIAL-CONTENTS is an obsolete alternative to
DEFAULT-VALUE. It normally should be nil in new code, except when
HIST is a cons. It is discussed in more detail below.
}
DEFUN ("read-command", Fread_command, Sread_command, 1, 2, 0,
- doc: /* Read the name of a command and return as a symbol.
+ doc: /* Read the name of a command and return it as a symbol.
Prompt with PROMPT. By default, return DEFAULT-VALUE or its first element
if it is a list. If DEFAULT-VALUE is omitted or nil, and the user enters
null input, return a symbol whose name is an empty string. */)
projects / emacs.git / commitdiff